Reverse Penny Drop Verification - Initiate Payment Links API

The following document highlights the details of the Initiate Payment Links API.

API Description

Objective

The Initiate Payment Links API generates multiple Unified Payments Interface(UPI) links for the penny drop transaction.

Input	Output
[Optional] The name of the user	Multiple UPI payment links (or a QR code) to initiate a penny drop transaction by the user. The complete list of output fields is provided under the Success Response Details section.

Next Step

Retrieve the bank account information of the user and the transaction status through the Retrieve Bank Details API.

API URL

https://ind.thomas.hyperverge.co/v1/reversePennyDrop

API Endpoint

reversePennyDrop

Overview

The Initiate Payment Links API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Method - `POST`

Authentication

You need a unique pair of application ID ( appId ) and application key ( appKey ) from HyperVerge to verify your identity for accessing the Initiate Payment Links API.

Headers

Header	Mandatory / Optional	Description	Input Format
Content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
transactionId	Mandatory	Unique ID for the customer journey	Any defined unique value mapped to a transaction in your business ecosystem

Inputs

The following table provides the details of the parameters required for the Initiate Payment Links API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
`name`	Optional	string	The name of the user. This value can assist in an additional name match verification against the account owner's name retrieved from the Retrieve Bank Details API	Not Applicable	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the Initiate Payment Links API:

curl --location --request POST 'https://ind.thomas.hyperverge.co/v1/reversePennyDrop' \
--header 'appid: <Enter_the_appId-Shared-by-HyperVerge>' \
--header 'appkey: <Enter_the_appKey-shared-by-HyperVerge>' \
--header 'transactionId : <Enter_the_Transaction_ID>' \
--header 'Content-Type: application/json' \
--data '{
    "name": "<Enter_the_name>"
}'

Success Response

The following code snippet demonstrates a success response from the Initiate Payment Links API:

{
  "status": "success",
  "statusCode": 200,
  "verificationId": "<VERIFICATION_ID>",
  "referenceId": "<REFERENCE_ID>",
  "validUpto": "<VALID_UPTO>",
  "upiLink": "<UPI_LINK>",
  "paymentLinks": {
      "gpay": "<GPAY_URL>",
      "bhim": "<BHIM_URL>",
      "paytm": "<PAYTM_URL>",
      "phonepe": "<PHONEPE_URL>",
      "cred": "<CRED_URL>",
      "amazonPay": "<AMAZON_URL>",
      "mobiKwik": "<MOBIKWIK_URL>",
      "qrCode": "<BASE64_ENCODED_QR_CODE>"
  },
  "metaData": {
      "requestId": "<Request_ID>"
  }
}

Success Response Details

The following table outlines the details of the success response from the Initiate Payment Links API:

Parameter	Type	Description
`status`	string	The status of the request
`statusCode`	integer	The HTTP status code returned for the request
`verificationId`	string	Unique identifier for the user
`referenceId`	string	Reference ID associated with the payment
`validUpto`	string (datetime)	The date and time until which the payment links are valid. The links are valid up to ten minutes from making the request.
`upiLink`	string	The intent link* enables users to select their preferred UPI application on their mobile device to complete the transaction
`paymentLinks`	object	Contains all the payment links for different UPI applications
`paymentLinks.gpay`	string	The intent link* redirects users to the Google Pay application to complete the transaction
`paymentLinks.bhim`	string	The intent link* redirects users to the BHIM application to complete the transaction
`paymentLinks.paytm`	string	The intent link* redirects users to the Paytm application to complete the transaction
`paymentLinks.phonepe`	string	The intent link* redirects users to the PhonePe application to complete the transaction
`paymentLinks.cred`	string	The intent link* redirects users to the Cred application to complete the transaction
`paymentLinks.amazonPay`	string	The intent link* redirects users to the AmazonPay application to complete the transaction
`paymentLinks.mobiKwik`	string	The intent link* redirects users to the MobiKwik application to complete the transaction
`paymentLinks.qrCode`	string	A base64-encoded representation of the QR code for the `upiLink`
`metaData`	object	Contains request and transaction identifiers
`requestId`	string	A unique identifier for the request

Info

*Intent link: A link that directs you to start an activity in another application. It enables seamless navigation and interaction across the applications.

Failure Response

The following code snippet demonstrates a failure response from the Initiate Payment Links API:

{
  "statusCode": 400,
  "status": "failure",
  "error": "verificationId already exists",
  "metaData": {
      "requestId": "<Request_ID>"
  }
}

The following are additional failure responses from the Initiate Payment Links API:

Verification ID Exists
Payment Link Already Created

{
  "statusCode": 400,
  "status": "failure",
  "error": "verificationId already exists",
  "metaData": {
      "requestId": "<Request_ID>"
  }
}

{
  "statusCode": 400,
  "error": {
    "message": "Created",
    "verificationId": "",
    "referenceId": "",
    "status": "CREATED",
    "addedOn": "",
    "processedOn": ""
  }
}

Error Responses

The following are some error responses from the Initiate Payment Links API:

Input Validation Error
Rate Limit Exceeded
Internal Server Error

{
  "message": "Input Validation Error: does not meet minimum length of 1",
  "statusCode": 400,
  "status": "failure"
}

{
  "statusCode": 429,
  "status": "failure",
  "error": "Rate limit exceeded"
}

{
    "statusCode": 500,
    "status": "failure",
    "error": "Internal Server Error"
}

Error Response Details

A failure or error response contains a failure status with a relevant status code and error message.
The following table lists all error responses:

Status Code	Error Message	Error Description	Error Resolution
400	verificationId already exists	The provided verification ID already exists in the system.	Use a different verification ID or wait for the existing verification to expire
400	Input Validation Error: does not meet minimum length of 1	The request did not meet the minimum length requirement of 1.	Ensure the input parameters meet the required validation criteria
400	Payment Link Already Created	The API has already created the payment links for the `appId`, `appKey` and `transactionId` combination.	Use a different transactionId or retrieve the existing payment links
401	Missing/Invalid credentials	The request is either missing the mandatory credentials or has invalid credentials.	Provide valid appId and appKey credentials in the request
429	Rate limit exceeded	You have exceeded the configured rate limit for transactions per minute.	Wait before making another request or contact the HyperVerge team to adjust rate limits
500	Internal Server Error	There was an error with HyperVerge's server	Please check the request headers or contact the HyperVerge team for resolution

API Description​

Objective​

Next Step​

API URL​

API Endpoint​

Overview​

Method - POST​

Authentication​

Headers​

Inputs​

Request​

Success Response​

Success Response Details​

Failure Response​

Error Responses​

Error Response Details​